\hypertarget{classduye_1_1_xml_handle}{\section{duye\-:\-:Xml\-Handle Class Reference}
\label{classduye_1_1_xml_handle}\index{duye\-::\-Xml\-Handle@{duye\-::\-Xml\-Handle}}
}


A G\-Xml\-Handle is a class that wraps a node pointer with null checks; this is an incredibly useful thing. Note that G\-Xml\-Handle is not part of the Gny\-Xml D\-O\-M structure. It is a separate utility class.  




{\ttfamily \#include $<$duye\-\_\-xml.\-h$>$}

\subsection*{Public Member Functions}
\begin{DoxyCompactItemize}
\item 
\hypertarget{classduye_1_1_xml_handle_ad8f20c3cbda416326e5fa4b01e849543}{\hyperlink{classduye_1_1_xml_handle_ad8f20c3cbda416326e5fa4b01e849543}{Xml\-Handle} (\hyperlink{classduye_1_1_xml_node}{Xml\-Node} $\ast$\hyperlink{classduye_1_1_xml_handle_a34202c8a1a7ba3bad454376bded10955}{node})}\label{classduye_1_1_xml_handle_ad8f20c3cbda416326e5fa4b01e849543}

\begin{DoxyCompactList}\small\item\em Create a handle from any node (at any depth of the tree.) This can be a null pointer. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_a87d9b1bfd27642642ce91fad541c9522}{\hyperlink{classduye_1_1_xml_handle_a87d9b1bfd27642642ce91fad541c9522}{Xml\-Handle} (const \hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} \&ref)}\label{classduye_1_1_xml_handle_a87d9b1bfd27642642ce91fad541c9522}

\begin{DoxyCompactList}\small\item\em Copy constructor. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_a340f92a52e622096042849b97704c543}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} {\bfseries operator=} (const \hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} \&ref)}\label{classduye_1_1_xml_handle_a340f92a52e622096042849b97704c543}

\item 
\hypertarget{classduye_1_1_xml_handle_aeaf0a3602fc378ab7166ff850a7edf77}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} \hyperlink{classduye_1_1_xml_handle_aeaf0a3602fc378ab7166ff850a7edf77}{first\-Child} () const }\label{classduye_1_1_xml_handle_aeaf0a3602fc378ab7166ff850a7edf77}

\begin{DoxyCompactList}\small\item\em Return a handle to the first child node. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_ad3285e5226211a181a45ae4c97ed3906}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} \hyperlink{classduye_1_1_xml_handle_ad3285e5226211a181a45ae4c97ed3906}{first\-Child} (const char $\ast$value) const }\label{classduye_1_1_xml_handle_ad3285e5226211a181a45ae4c97ed3906}

\begin{DoxyCompactList}\small\item\em Return a handle to the first child node with the given name. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_ae7fb9ef0bb17a19981693df6059ed58c}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} \hyperlink{classduye_1_1_xml_handle_ae7fb9ef0bb17a19981693df6059ed58c}{first\-Child\-Element} () const }\label{classduye_1_1_xml_handle_ae7fb9ef0bb17a19981693df6059ed58c}

\begin{DoxyCompactList}\small\item\em Return a handle to the first child element. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_a6235c95236a2c915d558af3ec458e80b}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} \hyperlink{classduye_1_1_xml_handle_a6235c95236a2c915d558af3ec458e80b}{first\-Child\-Element} (const char $\ast$value) const }\label{classduye_1_1_xml_handle_a6235c95236a2c915d558af3ec458e80b}

\begin{DoxyCompactList}\small\item\em Return a handle to the first child element with the given name. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_ad4e0843674c390084f3e34c9dd0efb99}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} \hyperlink{classduye_1_1_xml_handle_ad4e0843674c390084f3e34c9dd0efb99}{child} (const char $\ast$value, int index) const }\label{classduye_1_1_xml_handle_ad4e0843674c390084f3e34c9dd0efb99}

\begin{DoxyCompactList}\small\item\em Return a handle to the \char`\"{}index\char`\"{} child with the given name. The first child is 0, the second 1, etc. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_a4f2be890e71049ca05b575981cc221bd}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} \hyperlink{classduye_1_1_xml_handle_a4f2be890e71049ca05b575981cc221bd}{child} (int index) const }\label{classduye_1_1_xml_handle_a4f2be890e71049ca05b575981cc221bd}

\begin{DoxyCompactList}\small\item\em Return a handle to the \char`\"{}index\char`\"{} child. The first child is 0, the second 1, etc. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_ac7c47efc26a1bc69c354fec55f56010f}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} \hyperlink{classduye_1_1_xml_handle_ac7c47efc26a1bc69c354fec55f56010f}{child\-Element} (const char $\ast$value, int index) const }\label{classduye_1_1_xml_handle_ac7c47efc26a1bc69c354fec55f56010f}

\begin{DoxyCompactList}\small\item\em Return a handle to the \char`\"{}index\char`\"{} child element with the given name. The first child element is 0, the second 1, etc. Note that only G\-Xml\-Elements are indexed\-: other types are not counted. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_a5019b79fc90a5f9c78d09846fdfed51a}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} \hyperlink{classduye_1_1_xml_handle_a5019b79fc90a5f9c78d09846fdfed51a}{child\-Element} (int index) const }\label{classduye_1_1_xml_handle_a5019b79fc90a5f9c78d09846fdfed51a}

\begin{DoxyCompactList}\small\item\em Return a handle to the \char`\"{}index\char`\"{} child element. The first child element is 0, the second 1, etc. Note that only G\-Xml\-Elements are indexed\-: other types are not counted. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_a6d632819324671dc2cc0e5e36fe5b2ea}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} {\bfseries first\-Child} (const std\-::string \&value) const }\label{classduye_1_1_xml_handle_a6d632819324671dc2cc0e5e36fe5b2ea}

\item 
\hypertarget{classduye_1_1_xml_handle_ac7f7463b7fd336124ab643839c948c07}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} {\bfseries first\-Child\-Element} (const std\-::string \&value) const }\label{classduye_1_1_xml_handle_ac7f7463b7fd336124ab643839c948c07}

\item 
\hypertarget{classduye_1_1_xml_handle_a6c7ee9b66280de0b80a9578ac93ad6d6}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} {\bfseries child} (const std\-::string \&value, int index) const }\label{classduye_1_1_xml_handle_a6c7ee9b66280de0b80a9578ac93ad6d6}

\item 
\hypertarget{classduye_1_1_xml_handle_a38f5285940724b402218ee09e52d1f31}{\hyperlink{classduye_1_1_xml_handle}{Xml\-Handle} {\bfseries child\-Element} (const std\-::string \&value, int index) const }\label{classduye_1_1_xml_handle_a38f5285940724b402218ee09e52d1f31}

\item 
\hypertarget{classduye_1_1_xml_handle_ac7dc11cbc2ea7743a12eeb50c8937497}{\hyperlink{classduye_1_1_xml_node}{Xml\-Node} $\ast$ \hyperlink{classduye_1_1_xml_handle_ac7dc11cbc2ea7743a12eeb50c8937497}{to\-Node} () const }\label{classduye_1_1_xml_handle_ac7dc11cbc2ea7743a12eeb50c8937497}

\begin{DoxyCompactList}\small\item\em Return the handle as a \hyperlink{classduye_1_1_xml_node}{Xml\-Node}. This may return null. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_aaf7ed88ed4c65ffe47776f63f63e9811}{\hyperlink{classduye_1_1_xml_element}{Xml\-Element} $\ast$ \hyperlink{classduye_1_1_xml_handle_aaf7ed88ed4c65ffe47776f63f63e9811}{to\-Element} () const }\label{classduye_1_1_xml_handle_aaf7ed88ed4c65ffe47776f63f63e9811}

\begin{DoxyCompactList}\small\item\em Return the handle as a G\-Xml\-Element. This may return null. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_a2dfbc8f5f303e1ac5ea5ce06e56cd564}{\hyperlink{classduye_1_1_xml_text}{Xml\-Text} $\ast$ \hyperlink{classduye_1_1_xml_handle_a2dfbc8f5f303e1ac5ea5ce06e56cd564}{to\-Text} () const }\label{classduye_1_1_xml_handle_a2dfbc8f5f303e1ac5ea5ce06e56cd564}

\begin{DoxyCompactList}\small\item\em Return the handle as a \hyperlink{classduye_1_1_xml_text}{Xml\-Text}. This may return null. \end{DoxyCompactList}\item 
\hypertarget{classduye_1_1_xml_handle_ada5162b3aa12cf26c73e14b47795ab48}{\hyperlink{classduye_1_1_xml_unknown}{Xml\-Unknown} $\ast$ \hyperlink{classduye_1_1_xml_handle_ada5162b3aa12cf26c73e14b47795ab48}{to\-Unknown} () const }\label{classduye_1_1_xml_handle_ada5162b3aa12cf26c73e14b47795ab48}

\begin{DoxyCompactList}\small\item\em Return the handle as a G\-Xml\-Unknown. This may return null. \end{DoxyCompactList}\item 
\hyperlink{classduye_1_1_xml_node}{Xml\-Node} $\ast$ \hyperlink{classduye_1_1_xml_handle_a34202c8a1a7ba3bad454376bded10955}{node} () const 
\item 
\hyperlink{classduye_1_1_xml_element}{Xml\-Element} $\ast$ \hyperlink{classduye_1_1_xml_handle_acf58dcd905b9017606e7316fe22892ac}{element} () const 
\item 
\hyperlink{classduye_1_1_xml_text}{Xml\-Text} $\ast$ \hyperlink{classduye_1_1_xml_handle_a004c8d21525252331f4954a5e36ad54d}{text} () const 
\item 
\hyperlink{classduye_1_1_xml_unknown}{Xml\-Unknown} $\ast$ \hyperlink{classduye_1_1_xml_handle_a405bce4aa913198d051a2a573e8b47aa}{unknown} () const 
\end{DoxyCompactItemize}


\subsection{Detailed Description}
A G\-Xml\-Handle is a class that wraps a node pointer with null checks; this is an incredibly useful thing. Note that G\-Xml\-Handle is not part of the Gny\-Xml D\-O\-M structure. It is a separate utility class. 

Take an example\-: \begin{DoxyVerb} * <Document>
 * <Element attributeA = "valueA">
 * <Child attributeB = "value1" />
 * <Child attributeB = "value2" />
 * </Element>
 * <Document>
 * \end{DoxyVerb}


Assuming you want the value of \char`\"{}attribute\-B\char`\"{} in the 2nd \char`\"{}\-Child\char`\"{} element, it's very easy to write a {\itshape lot} of code that looks like\-:

\begin{DoxyVerb} */
 /*
GXmlElement* root = document.FirstChildElement( "Document" );
if ( root )
{
GXmlElement* element = root->FirstChildElement( "Element" );
if ( element )
{
    GXmlElement* child = element->FirstChildElement( "Child" );
    if ( child )
    {
        GXmlElement* child2 = child->NextSiblingElement( "Child" );
        if ( child2 )
        {
            // Finally do something useful.\end{DoxyVerb}


And that doesn't even cover \char`\"{}else\char`\"{} cases. G\-Xml\-Handle addresses the verbosity of such code. A G\-Xml\-Handle checks for null pointers so it is perfectly safe and correct to use\-:

\begin{DoxyVerb}    GXmlHandle docHandle( &document );
    GXmlElement* child2 = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", 1 ).ToElement();
    if ( child2 )
    {
        // do something useful\end{DoxyVerb}


Which is M\-U\-C\-H more concise and useful.

It is also safe to copy handles -\/ internally they are nothing more than node pointers. \begin{DoxyVerb}    GXmlHandle handleCopy = handle;\end{DoxyVerb}


What they should not be used for is iteration\-:

\begin{DoxyVerb}    int i=0; 
    while ( true )
    {
        GXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).Child( "Child", i ).ToElement();
        if ( !child )
            break;
        // do something
        ++i;
    }\end{DoxyVerb}


It seems reasonable, but it is in fact two embedded while loops. The Child method is a linear walk to find the element, so this code would iterate much more than it needs to. Instead, prefer\-:

\begin{DoxyVerb}    GXmlElement* child = docHandle.FirstChild( "Document" ).FirstChild( "Element" ).FirstChild( "Child" ).ToElement();

    for( child; child; child=child->NextSiblingElement() )
    {
        // do something
    }\end{DoxyVerb}
 

\subsection{Member Function Documentation}
\hypertarget{classduye_1_1_xml_handle_acf58dcd905b9017606e7316fe22892ac}{\index{duye\-::\-Xml\-Handle@{duye\-::\-Xml\-Handle}!element@{element}}
\index{element@{element}!duye::XmlHandle@{duye\-::\-Xml\-Handle}}
\subsubsection[{element}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Xml\-Element}$\ast$ duye\-::\-Xml\-Handle\-::element (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}}\label{classduye_1_1_xml_handle_acf58dcd905b9017606e7316fe22892ac}
\begin{DoxyRefDesc}{Deprecated}
\item[\hyperlink{deprecated__deprecated000002}{Deprecated}]use To\-Element. Return the handle as a G\-Xml\-Element. This may return null. \end{DoxyRefDesc}
\hypertarget{classduye_1_1_xml_handle_a34202c8a1a7ba3bad454376bded10955}{\index{duye\-::\-Xml\-Handle@{duye\-::\-Xml\-Handle}!node@{node}}
\index{node@{node}!duye::XmlHandle@{duye\-::\-Xml\-Handle}}
\subsubsection[{node}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Xml\-Node}$\ast$ duye\-::\-Xml\-Handle\-::node (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}}\label{classduye_1_1_xml_handle_a34202c8a1a7ba3bad454376bded10955}
\begin{DoxyRefDesc}{Deprecated}
\item[\hyperlink{deprecated__deprecated000001}{Deprecated}]use To\-Node. Return the handle as a \hyperlink{classduye_1_1_xml_node}{Xml\-Node}. This may return null. \end{DoxyRefDesc}
\hypertarget{classduye_1_1_xml_handle_a004c8d21525252331f4954a5e36ad54d}{\index{duye\-::\-Xml\-Handle@{duye\-::\-Xml\-Handle}!text@{text}}
\index{text@{text}!duye::XmlHandle@{duye\-::\-Xml\-Handle}}
\subsubsection[{text}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Xml\-Text}$\ast$ duye\-::\-Xml\-Handle\-::text (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}}\label{classduye_1_1_xml_handle_a004c8d21525252331f4954a5e36ad54d}
\begin{DoxyRefDesc}{Deprecated}
\item[\hyperlink{deprecated__deprecated000003}{Deprecated}]use To\-Text() Return the handle as a \hyperlink{classduye_1_1_xml_text}{Xml\-Text}. This may return null. \end{DoxyRefDesc}
\hypertarget{classduye_1_1_xml_handle_a405bce4aa913198d051a2a573e8b47aa}{\index{duye\-::\-Xml\-Handle@{duye\-::\-Xml\-Handle}!unknown@{unknown}}
\index{unknown@{unknown}!duye::XmlHandle@{duye\-::\-Xml\-Handle}}
\subsubsection[{unknown}]{\setlength{\rightskip}{0pt plus 5cm}{\bf Xml\-Unknown}$\ast$ duye\-::\-Xml\-Handle\-::unknown (
\begin{DoxyParamCaption}
{}
\end{DoxyParamCaption}
) const\hspace{0.3cm}{\ttfamily [inline]}}}\label{classduye_1_1_xml_handle_a405bce4aa913198d051a2a573e8b47aa}
\begin{DoxyRefDesc}{Deprecated}
\item[\hyperlink{deprecated__deprecated000004}{Deprecated}]use To\-Unknown() Return the handle as a G\-Xml\-Unknown. This may return null. \end{DoxyRefDesc}


The documentation for this class was generated from the following file\-:\begin{DoxyCompactItemize}
\item 
Z\-:/duye/src/duyebase/utils/duye\-\_\-xml.\-h\end{DoxyCompactItemize}
